///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.wrappers
{
/** Implemented by wrappers that support all standard operations (<code>create
 * </code>, <code>destroy</code>, <code>edit</code>, <code>prepare</code>, and
 * <code>read</code>). **/
public interface IStandardWrapper extends IWrapperBase
{
	/**
	 * Creates a new record.
	 * 
	 * <p>Typically, the XML template for content is aquired from a call to
	 * <code>prepare</code>.</p>
	 * 
	 * <p>Summit requires that the <code>content</code> contain a 
	 * <code>project-id</code> element with a valid project id.</p>
	 * 
	 * @param content XML representing the resource.
	 */  
	function create(content:XML):void;
	
	/**
	 * Deletes an existing record.
	 * 
	 * @param id The id of the record to delete.
	 */
	function destroy(id:String):void;
	
	/**
	 * Gets XML for a single existing record.
	 * 
	 * <p>The XML returned is prefilled with the existing values for 
	 * the identified record, and should be resubmitted via 
	 * <code>update</code>.</p>
	 * 
	 * @param id The id of the record to retrieve for edit.
	 * @param projectId The id of the project associated with the record.
	 */
	function edit(id:String, projectId:String):void;
	
	/**
	 * Gets an XML template of a resource for a parent.
	 * 
	 * <p>The provided <code>parentId</code> is typically the id of a project,
	 * however in other cases the id is a parent component, such as a 
	 * todo-list-id. Check the specific implementation for requirements.</p>
	 *  
	 * <p>The template returned can be submitted through
	 * <code>create</code> to make a new resource record.</p>
	 * 
	 * @param parentId The id of the parent record that will ultimately 
	 * receive the record.
	 */
	function prepare(parentId:String):void;
	
	/** Gets a specific record from the Basecamp store.
	 * 
	 * @param id
	 * The id of the record to read.
	 * @param projectId
	 * The id of the project the record is associated with.
	 */
	function read(id:String, projectId:String):void;
	
	/** Updates an existing record.
	 * 
	 * <p>A record retrieved from <code>edit</code> is submitted to 
	 * <code>update</code> to change the record on the server.</p>
	 * 
	 * <p>The <code>id</code> element in <code>content</code> must refer to
	 * an existing resource.</p>
	 * 
	 * @param content 
	 * XML with new values to update the existing record.
	 */
	function update(content:XML):void;
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //